lib/content/isCompletedRun.ts (1)

8-11: Add meaningful JSDoc text (current block is effectively empty).

On Line 8-11, the comment exists but doesn’t explain behavior or the run parameter. Please add a short summary and a concrete @param description so the docs are actually useful.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/isCompletedRun.ts` around lines 8 - 11, Update the empty JSDoc
block above the isCompletedRun function to include a short summary sentence
describing what the function does (e.g., checks whether a run is finished), a
concrete `@param` entry for the run parameter explaining expected shape or
properties used (e.g., status field or timestamps) and how it is interpreted,
and an `@returns` description specifying the boolean result and what true/false
mean; reference the isCompletedRun identifier so the doc directly documents that
function's behavior.

lib/github/getRepoGitModules.ts (1)

7-12: Fix inconsistent JSDoc param paths for destructured input.

Line 7, Line 11, and Line 12 add nested tags (owner.owner, owner.repo, owner.branch) that conflict with the existing flat tags (owner, repo, branch). This makes the docs ambiguous for IDE/tooling.

Suggested JSDoc cleanup

 /**
  * Fetches and parses .gitmodules from a GitHub repository.
  * Uses the GitHub Contents API (works for both public and private repos).
  *
- * `@param` owner.owner
- * `@param` owner - The GitHub repository owner
- * `@param` repo - The GitHub repository name
- * `@param` branch - The branch to fetch from
- * `@param` owner.repo
- * `@param` owner.branch
+ * `@param` params - Repository coordinates
+ * `@param` params.owner - The GitHub repository owner
+ * `@param` params.repo - The GitHub repository name
+ * `@param` params.branch - The branch to fetch from
  * `@returns` Array of submodule entries, or null if .gitmodules doesn't exist or fetch fails
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/github/getRepoGitModules.ts` around lines 7 - 12, The JSDoc for
getRepoGitModules.ts uses inconsistent param names (both flat tags like `@param`
owner/@param repo/@param branch and erroneous nested tags like `@param`
owner.owner/@param owner.repo/@param owner.branch); remove the nested/duplicate
tags and ensure the JSDoc matches the function signature (document the
destructured param either as a single object with a type description or keep
separate `@param` entries for owner, repo, branch) so that only the correct
identifiers used in the function (owner, repo, branch) are documented.

lib/supabase/files/createFileRecord.ts (1)

28-30: Clarify @param params with field-level intent.

On Line 29, @param params is too terse for an exported Supabase domain function. Add a short object-level description plus key fields to keep the contract self-documenting.

Suggested JSDoc improvement

 /**
  * Create a file record in the database
  *
- * `@param` params
+ * `@param` params - File metadata payload used to persist a row in `files`.
+ * `@param` params.ownerAccountId - Owning account ID.
+ * `@param` params.artistAccountId - Artist account ID associated with the file.
+ * `@param` params.storageKey - Storage object key/path.
+ * `@param` params.fileName - Original or display file name.
+ * `@param` params.mimeType - Optional MIME type.
+ * `@param` params.sizeBytes - Optional file size in bytes.
+ * `@param` params.description - Optional description.
+ * `@param` params.tags - Optional tags; defaults to [] when omitted.
  */

As per coding guidelines: “Supabase database functions should import from @/lib/supabase/serverClient and follow the documented pattern with JSDoc comments, error handling, and return types”.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/supabase/files/createFileRecord.ts` around lines 28 - 30, The JSDoc for
the exported Supabase function createFileRecord is too terse—replace the generic
"@param params" with an object-level description and explicit key descriptions
(e.g., params.bucket, params.key or path, params.size,
params.mimeType/contentType, params.userId/uploaderId, params.metadata/extra) so
callers know the contract; update the comment block above createFileRecord to
list each field, types and short intent (required/optional) and ensure it
follows the project pattern for Supabase domain functions importing from
"@/lib/supabase/serverClient".

lib/composio/getCallbackUrl.ts (1)

22-22: Complete and reorder the new @param options JSDoc entry.

At Line 22, @param options has no description and comes after options.destination/options.roomId. Put the parent param first and add a short description for cleaner generated docs.

✏️ Suggested doc-only cleanup

- * `@param` options.destination - Where to redirect: "chat" or "connectors"
- * `@param` options.roomId - For chat destination, the room ID to return to
- * `@param` options
+ * `@param` options - Callback URL options
+ * `@param` options.destination - Where to redirect: "chat" or "connectors"
+ * `@param` options.roomId - For chat destination, the room ID to return to

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/composio/getCallbackUrl.ts` at line 22, Move the JSDoc `@param` for the
parent "options" above the child params (options.destination and options.roomId)
and add a short description; update the JSDoc block for the getCallbackUrl (or
the exported function in getCallbackUrl.ts) so it lists "@param options - an
object containing callback configuration" (or similar concise text) before
"@param options.destination" and "@param options.roomId" to keep param order
logical and improve generated docs.

lib/admins/privy/getLatestVerifiedAt.ts (1)

8-8: Use repository-approved terminology in JSDoc and add a param description.

Line 8 introduces @param user, but the project standard requires account terminology. Please also include a short description for clarity.

🔧 Suggested update

- * `@param` user
+ * `@param` account Privy account object containing linked_accounts metadata.
...
-export function getLatestVerifiedAt(user: User): number | null {
-  const linkedAccounts = user.linked_accounts;
+export function getLatestVerifiedAt(account: User): number | null {
+  const linkedAccounts = account.linked_accounts;

As per coding guidelines, "Use 'account' terminology, never 'entity' or 'user'."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/admins/privy/getLatestVerifiedAt.ts` at line 8, Update the JSDoc for
getLatestVerifiedAt to use the repository-approved terminology by renaming the
param from "user" to "account" and add a short description; specifically, change
the `@param` tag to "@param account" and include one-line text describing that
account is the Account object or identifier passed into getLatestVerifiedAt so
the doc follows the project's "account" terminology and clarifies the parameter
purpose.

lib/supabase/storage/uploadFileByKey.ts (1)

7-11: Add meaningful descriptions to each JSDoc @param.

The new tags are present, but without descriptions they don’t improve API clarity for callers. Please document expected format/behavior (e.g., key path semantics, default contentType, default upsert=false).

📝 Proposed JSDoc improvement

 /**
  * Upload file to Supabase storage by key
  *
- * `@param` key
- * `@param` file
- * `@param` options
- * `@param` options.contentType
- * `@param` options.upsert
+ * `@param` key Storage object key/path inside the configured bucket.
+ * `@param` file File or Blob payload to upload.
+ * `@param` options Optional upload settings.
+ * `@param` options.contentType MIME type to store with the object (defaults to `application/octet-stream`).
+ * `@param` options.upsert Whether to overwrite an existing object at the same key (defaults to `false`).
  */

As per coding guidelines, "Supabase database functions should import from @/lib/supabase/serverClient and follow the documented pattern with JSDoc comments, error handling, and return types".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/supabase/storage/uploadFileByKey.ts` around lines 7 - 11, Update the
JSDoc for the upload function (e.g., uploadFileByKey) to include meaningful
descriptions for each param: describe key as the storage path/OCI-style path or
bucket-relative path semantics (e.g., "bucket/path/to/file.ext"), file as the
File/Blob or Buffer to be uploaded, options as an optional object controlling
upload behavior, options.contentType with its default (e.g.,
"application/octet-stream" or infer from filename) and expected MIME string
format, and options.upsert with default false and that it controls overwrite
behavior; also ensure the function follows the Supabase pattern by importing the
server client from "@/lib/supabase/serverClient" and that the JSDoc mentions
thrown errors/return type consistent with other Supabase helpers (e.g., upload
result or error).

lib/flamingo/getFlamingoPresetsHandler.ts (1)

13-13: Complete the JSDoc @param tag with a description.

The @param tag is missing a description, which reduces its documentation value. While TypeScript provides type information, a brief description helps clarify the parameter's purpose and maintains consistency with the @returns tag below.

📝 Suggested improvement

- * `@param` request
+ * `@param` request - The incoming HTTP request object containing headers for authentication.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/flamingo/getFlamingoPresetsHandler.ts` at line 13, Add a concise
description to the JSDoc `@param` for the request parameter in
getFlamingoPresetsHandler: state what the request represents (e.g., incoming
Express/HTTP request or handler input), what properties are expected/used (if
any), and its role in the function; update the JSDoc `@param` line to read
something like "@param request - the incoming request object containing [brief
properties or purpose]" so it matches the existing `@returns` documentation and
clarifies the parameter's purpose.

lib/catalog/getCatalogs.ts (1)

11-14: Complete the JSDoc documentation.

The JSDoc comment is incomplete—it lacks a function description, parameter details, and return type documentation. Comprehensive documentation improves maintainability and helps other developers understand the function's purpose, inputs, and outputs.

📝 Proposed fix for complete JSDoc

 /**
- *
- * `@param` accountId
+ * Fetches all catalogs associated with a specific account.
+ *
+ * `@param` accountId - The unique identifier of the account whose catalogs to retrieve
+ * `@returns` A promise that resolves to a CatalogsResponse containing the list of catalogs
+ * `@throws` {Error} When the HTTP request fails or the API returns an error status
  */
 export async function getCatalogs(accountId: string): Promise<CatalogsResponse> {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/catalog/getCatalogs.ts` around lines 11 - 14, Add complete JSDoc for the
getCatalogs function: write a one-line description of what getCatalogs does, add
`@param` accountId with its type and description, document the return value (e.g.,
Promise of the catalog array or specific Catalog type) with `@returns` and
describe possible thrown errors or null cases, and include any side effects;
place this above the getCatalogs function declaration in
lib/catalog/getCatalogs.ts so the function signature and return type
(getCatalogs) are clearly described for callers and maintainers.

lib/coding-agent/handleMergeSuccess.ts (1)

10-11: Incomplete JSDoc parameter documentation.

The @param state tag lacks a description. While TypeScript provides type information, a brief description enhances readability and helps developers understand the parameter's purpose without inspecting the type definition.

📝 Suggested improvement

 *
-* `@param` state
+* `@param` state - The coding agent thread state containing PR and snapshot information for cleanup
 */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/coding-agent/handleMergeSuccess.ts` around lines 10 - 11, The JSDoc for
the handleMergeSuccess function has an incomplete `@param` tag for "state"; update
the comment above handleMergeSuccess in lib/coding-agent/handleMergeSuccess.ts
to add a concise description of what the "state" parameter represents (e.g.,
current merge operation context, contains branch names, commit metadata, and
status flags) so readers can understand its purpose without opening the type
definition.

lib/coding-agent/parseMergeActionId.ts (2)

4-5: Consider adding a description to the @param tag.

The JSDoc @param annotation lacks a description. Adding semantic information about the parameter's expected format helps improve documentation clarity.

📝 Suggested enhancement

 *
-* `@param` actionId
+* `@param` actionId - The action ID string to parse (format: "merge_pr:owner/repo#123")
 */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/coding-agent/parseMergeActionId.ts` around lines 4 - 5, The JSDoc for
parseMergeActionId is missing a description for the `@param` actionId; update the
function's JSDoc block (the one above parseMergeActionId) to describe what
actionId should contain (e.g., expected type, format, and any accepted patterns
such as "merge:<repo>:<prId>" or a UUID) so callers know the input shape and
constraints.

---

7-11: Consider consolidating similar parsing logic.

Both parseMergeActionId and parseMergeTestToMainActionId follow a similar pattern: validate a prefix/format, extract repository information, and return null on mismatch. While they handle different formats, a shared utility function for prefix-based action ID parsing could reduce duplication and improve maintainability. As per coding guidelines, the DRY principle encourages consolidating similar logic into shared utilities.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/coding-agent/parseMergeActionId.ts` around lines 7 - 11,
parseMergeActionId duplicates parsing logic used by
parseMergeTestToMainActionId; create a shared utility (e.g.,
parsePrefixedActionId or parseActionIdWithRegex) that accepts the expected
prefix/regex and the actionId string, performs the match, and returns the same
shape ({ repo, number } or null) on mismatch; update parseMergeActionId and
parseMergeTestToMainActionId to call this utility (preserve their public names
and return types) and remove the inline regex/match logic from both functions to
avoid duplication.

lib/coding-agent/parseMergeTestToMainActionId.ts (1)

4-5: Consider adding a description to the @param tag.

The JSDoc @param annotation is present but lacks a description. While TypeScript provides type information, adding a semantic description helps documentation consumers understand the parameter's purpose and expected format.

📝 Suggested enhancement

 *
-* `@param` actionId
+* `@param` actionId - The action ID string to parse (format: "merge_test_to_main:owner/repo")
 */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/coding-agent/parseMergeTestToMainActionId.ts` around lines 4 - 5, The
JSDoc for the function in parseMergeTestToMainActionId.ts is missing a
description for the `@param` actionId; update the JSDoc block for the function
(the symbol handling actionId in parseMergeTestToMainActionId) to include a
short semantic description of what actionId represents and its expected format
(e.g., "actionId: the workflow run/action identifier string used to map a
merge-from-test action to the main action, expected in the form
'owner/repo#runId' or similar"). Ensure the `@param` line describes purpose and
any format or validation assumptions.

lib/spotify/getSpotifyFollowers.ts (1)

62-65: Consider letting the caller handle error logging.

The console.error on line 63 logs before re-throwing the error. In library functions, it's often better to let the caller decide how to handle logging, as they may have their own error handling or logging infrastructure. This also avoids duplicate logs if the caller logs the error as well.

♻️ Suggested refactor to remove console logging

   } catch (error) {
-    console.error(`Error fetching Spotify followers for "${artistName}":`, error);
     throw error;
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/spotify/getSpotifyFollowers.ts` around lines 62 - 65, The catch block
inside getSpotifyFollowers currently calls console.error before re-throwing the
error, which forces logging and can cause duplicate logs; remove the
console.error(...) call in the catch of getSpotifyFollowers and simply re-throw
the error so callers can handle or log it according to their own
logging/monitoring strategy.

lib/content/contentTemplates.ts (1)

28-31: Complete the JSDoc documentation.

The JSDoc comment is essentially a stub with no function description, no parameter description, and no return value documentation. If we're adding documentation, it should provide meaningful information about the function's purpose, parameters, and return value.

📝 Suggested complete JSDoc

 /**
- *
- * `@param` template
+ * Checks whether the given template name is supported.
+ * `@param` template - The content template name to validate
+ * `@returns` True if the template exists in CONTENT_TEMPLATES, false otherwise
  */
 export function isSupportedContentTemplate(template: string): boolean {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/contentTemplates.ts` around lines 28 - 31, Replace the stub JSDoc
above the function in lib/content/contentTemplates.ts with a full description:
add a one-line summary of what the function does, document the parameter
"template" with its expected type and shape (e.g., string | TemplateObject) and
purpose, and add an `@returns` tag describing the return type and what is returned
(e.g., formatted template string or TemplateResult). Also include any thrown
errors or side effects if applicable and a short example or note about accepted
template formats to aid callers.

lib/trigger/triggerCreateContent.ts (1)

19-20: Complete the JSDoc parameter description.

The @param tag should include a description explaining what the payload contains. Consider adding a brief description that helps developers understand the parameter's purpose.

📝 Proposed enhancement to JSDoc

 /**
  * Triggers the create-content task in Trigger.dev.
  *
- * `@param` payload
+ * `@param` payload - The content creation configuration including account, artist, template, and rendering options
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/trigger/triggerCreateContent.ts` around lines 19 - 20, Update the JSDoc
for the function in triggerCreateContent.ts by completing the `@param` tag for the
payload parameter: describe what properties the payload contains (e.g., content
data, metadata, authorId, or any expected fields), the expected types/shape
(briefly), and its purpose (what the function does with the payload) so future
developers can understand how to call triggerCreateContent and what to pass in.

lib/slack/getBotChannels.ts (1)

12-13: Consider adding parameter descriptions to the JSDoc.

The @param token annotation lacks a description of what the token represents.

📝 Suggested improvement

 /**
  * Returns all channels the bot is a member of, paginating through all results.
  *
- * `@param` token
+ * `@param` token - The Slack bot token for authentication
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/slack/getBotChannels.ts` around lines 12 - 13, Update the JSDoc for
getBotChannels to document the token parameter: describe that `token` is the
Slack Bot OAuth access token (a string used to authenticate API requests) and
note any expected format or scope requirements; update the `@param token` line
in the comment above the getBotChannels function to include this description and
keep style consistent with other JSDoc entries in the file.

lib/slack/getBotUserId.ts (1)

11-12: Consider adding parameter descriptions to the JSDoc.

The @param token annotation was added but lacks a description. Complete JSDoc documentation improves developer experience by explaining what kind of token is expected.

📝 Suggested improvement

 /**
  * Returns the authenticated bot's Slack user ID via auth.test.
  *
- * `@param` token
+ * `@param` token - The Slack bot token for authentication
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/slack/getBotUserId.ts` around lines 11 - 12, Update the JSDoc for the
getBotUserId function to include a clear description for the `@param` token tag
(e.g., that it expects a Slack Bot/User OAuth access token or similar), and if
missing add descriptions for other tags like `@returns` to clarify what the
function returns; locate the JSDoc immediately above the getBotUserId function
in lib/slack/getBotUserId.ts and replace the bare "@param token" with a short
explanatory sentence describing the expected token format and purpose.

lib/slack/getSlackUserInfo.ts (1)

19-21: Consider adding parameter descriptions to the JSDoc.

Both @param annotations were added without descriptions. Adding descriptions helps developers understand what values to provide.

📝 Suggested improvement

 /**
  * Fetches a Slack account's display name and avatar by their Slack ID.
  *
- * `@param` token
- * `@param` userId
+ * `@param` token - The Slack bot token for authentication
+ * `@param` userId - The Slack user ID to fetch information for
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/slack/getSlackUserInfo.ts` around lines 19 - 21, Add clear descriptions
for the JSDoc `@param` annotations in getSlackUserInfo (token and userId) so
callers know expected values; update the JSDoc above the getSlackUserInfo
function to describe that token is the Slack OAuth/Bot token used for API
authentication and userId is the Slack user ID (e.g., "U123...") whose profile
is being fetched, and optionally note expected formats or examples and whether
either parameter is required.

app/api/coding-agent/[platform]/route.ts (2)

13-14: Confusing JSDoc parameter notation.

The @param params.params tag appears before @param params in the documentation, which is confusing and doesn't follow JSDoc best practices. Additionally, the nested property reference lacks a description.

Consider either:

1. Removing the redundant params.params line since params already describes the route parameters
2. If documenting the nested structure, provide descriptions and maintain proper ordering (parent before children)

📝 Suggested JSDoc improvement

 /**
  * GET /api/coding-agent/[platform]
  *
  * Handles webhook verification handshakes (e.g. WhatsApp hub.challenge).
  *
  * `@param` request - The incoming verification request
- * `@param` params.params
  * `@param` params - Route params containing the platform name
+ * `@param` params.params - Awaitable promise resolving to the platform identifier
  */

Or more simply:

 /**
  * GET /api/coding-agent/[platform]
  *
  * Handles webhook verification handshakes (e.g. WhatsApp hub.challenge).
  *
  * `@param` request - The incoming verification request
- * `@param` params.params
- * `@param` params - Route params containing the platform name
+ * `@param` params - Route params promise containing the platform identifier
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/coding-agent/`[platform]/route.ts around lines 13 - 14, The JSDoc for
the route handler has a redundant/confusing tag: remove the incorrect "@param
params.params" line or replace it by documenting the nested property properly;
update the block that documents the route parameter `params` (the route handler
param named params) so the parent `@param params` appears before any child
properties and, if you keep a nested tag, use a property-style tag (e.g.,
"@param params.platform - description") with a short description for the nested
field to clarify the structure.

---

7-61: JSDoc parameter tags across this PR lack descriptions.

Throughout this file and the entire PR, @param tags have been added without descriptions. JSDoc documentation should provide meaningful context beyond what the TypeScript signature already conveys. Empty @param tags offer no value to developers and can actually clutter the documentation.

Best practices for JSDoc:

• Include concise descriptions that explain the parameter's purpose or constraints
• If the parameter is self-evident, a brief phrase still helps (e.g., @param catalogId - The unique catalog identifier)
• Omit @param tags entirely if you can't provide useful descriptions—TypeScript types already document the shape

This applies to all files in this PR: getContentValidateHandler.ts, getAccountArtistIds.ts, validateGetContentValidateQuery.ts, getCatalogSongs.ts, getCutoffMs.ts, getArtistContentReadiness.ts, and getArtistFileTree.ts.

📚 Examples of meaningful JSDoc

Before (current):

/**
 * `@param` catalogId
 * `@param` pageSize
 * `@param` page
 */
export async function getCatalogSongs(
  catalogId: string,
  pageSize: number = 100,
  page: number = 1,
): Promise<CatalogSongsResponse>

After (improved):

/**
 * Fetches a paginated list of songs from a catalog.
 * 
 * `@param` catalogId - The unique identifier of the catalog
 * `@param` pageSize - Number of songs per page (default: 100)
 * `@param` page - Page number for pagination (default: 1)
 * `@param` artistName - Optional filter to show only songs by a specific artist
 */
export async function getCatalogSongs(
  catalogId: string,
  pageSize: number = 100,
  page: number = 1,
  artistName?: string,
): Promise<CatalogSongsResponse>

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/coding-agent/`[platform]/route.ts around lines 7 - 61, The JSDoc
`@param` tags in this file (e.g., GET, POST handlers) and across the listed files
(getContentValidateHandler.ts, getAccountArtistIds.ts,
validateGetContentValidateQuery.ts, getCatalogSongs.ts, getCutoffMs.ts,
getArtistContentReadiness.ts, getArtistFileTree.ts) are empty—either add concise
descriptions for each parameter (e.g., "request - incoming NextRequest", "params
- route params containing the platform name", or "catalogId - the unique catalog
identifier", "pageSize - number of items per page (default: 100)") or remove the
`@param` entries entirely when the TypeScript signature is self-explanatory;
update the JSDoc blocks for functions like GET, POST and getCatalogSongs to
include these short descriptions so docs are meaningful and not cluttered.

lib/emails/processAndSendEmail.ts (1)

37-39: Complete the JSDoc parameter description.

The @param input tag was added but lacks a description, which reduces its documentation value. Consider adding a meaningful description or documenting the nested properties.

📝 Suggested enhancement

 *
-* `@param` input
+* `@param` input - Email configuration including recipients, subject, content, and optional room context

Or for more detailed documentation:

 *
-* `@param` input
+* `@param` input - Email configuration object
+* `@param` input.to - Recipient email addresses
+* `@param` input.subject - Email subject line
+* `@param` input.text - Plain text content (converted to HTML via markdown)
+* `@param` input.html - Pre-formatted HTML content
+* `@param` input.room_id - Optional room ID for footer personalization

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/emails/processAndSendEmail.ts` around lines 37 - 39, Update the JSDoc for
the processAndSendEmail function by replacing the empty "@param input" tag with
a concise description of the input parameter and its expected shape; either list
the key properties the email input object must contain (for example recipient,
subject, body, cc/bcc, attachments, metadata) or reference the TypeScript
interface/type used for validation (if one exists) so consumers know what to
pass into processAndSendEmail.

lib/credits/getCreditUsage.ts (1)

11-46: Consider refactoring for Single Responsibility Principle.

The function currently handles three distinct concerns: model retrieval, token extraction, and cost calculation. Consider splitting this into focused utilities:

• extractTokenCounts(usage: LanguageModelUsage) - handles SDK version compatibility
• calculateCost(inputTokens: number, outputTokens: number, pricing: ModelPricing) - pure calculation
• getCreditUsage - orchestrates the above

This would improve testability, reusability, and maintainability. Additionally, the current approach of returning 0 on all error paths silently masks failures—callers can't distinguish between "no cost" and "calculation failed." Consider returning { success: boolean, cost: number, error?: string } or throwing errors for truly exceptional cases.

As per coding guidelines: "Apply Single Responsibility Principle (SRP): one exported function per file; each file should do one thing well" and "For domain functions, ensure: Single responsibility per function."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/credits/getCreditUsage.ts` around lines 11 - 46, Split getCreditUsage
into three responsibilities: add extractTokenCounts(usage: LanguageModelUsage)
to normalize inputTokens/outputTokens from SDK v2/v3, add
calculateCost(inputTokens: number, outputTokens: number, pricing: ModelPricing)
as a pure function that returns the numeric cost, and refactor getCreditUsage to
orchestrate: call getModel(modelId), call extractTokenCounts, validate
model.pricing, call calculateCost and return a structured result (e.g., {
success: boolean, cost: number, error?: string }) instead of always returning 0
on errors; update error paths to populate the error field (or throw for truly
exceptional cases) and keep exported functions single-responsibility.

lib/launch/validateLaunchBody.ts (1)

25-44: Clean validation function, minor naming consideration.

The validation function follows the established pattern well: safeParse, early return on error with NextResponse, and return validated data on success.

One small consideration: missing_fields (Line 33) receives firstError.path, but Zod errors aren't exclusively about missing fields — they could be type mismatches or constraint violations like min(1). A name like error_path or field_path would be more accurate, though this is a minor nitpick.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/launch/validateLaunchBody.ts` around lines 25 - 44, The response object
in validateLaunchBody returns a property named missing_fields but Zod
issues.path can represent type/constraint errors too; rename the property to a
more accurate name like error_path (or field_path) and update the returned JSON
key (and any consumers) accordingly in validateLaunchBody so it reflects the
generic error path rather than implying only missing fields.